home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / pcrob13.zip / PCROBOTS.DOC < prev    next >
Text File  |  1992-11-01  |  74KB  |  2,203 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.             PCROBOTS V1.3 By P.D.Smith (psmithb@CIX) 1992
  9.             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10.  
  11.             Introduction
  12.             ~~~~~~~~~~~~~
  13.  
  14.             PCROBOTS is an adaptation of CROBOTS by Tom Poindexter. This
  15.             version has more features, and allows for much more
  16.             intelligent robots. It is not limited to any particular
  17.             language; C, Pascal,Compiled Basic, 8086 Assembler etc are
  18.             all possible. The only limitation is that it must be run on
  19.             an IBM PC Compatible.
  20.  
  21.             PCRobots uses 'robots' which are actually MsDos .COM or .EXE
  22.             programs. Each program is allocated 64k for data, program &
  23.             stack requirements. This is the main limiting factor for the
  24.             number of robots being run at once. If only conventional RAM
  25.             is used a maximum of 7-8 robots is possible, depending on
  26.             your system. However, with V1.3, EMS memory can be used.
  27.             This allows up to 20 robots at once.
  28.  
  29.             PCRobots allows a large user defined arena, with obstacles
  30.             in it, it also allows inter-robot communication to allow
  31.             teamwork between robots. PCROBOTS uses a cooperative
  32.             multitasker to share the processor between the robots, the
  33.             way this works means that robots can do lots of calculations
  34.             and planning without being penalised.
  35.  
  36.             Robots are configurable, this means that if your program
  37.             suits a fast agile robot, but one which doesn't need a long
  38.             cannon range, then you can configure the robot to make use
  39.             of this. Alternatively, you may want a slow robot with lots
  40.             of armour, this is also possible
  41.  
  42.             Hardware Requirements
  43.             ~~~~~~~~~~~~~~~~~~~~~~
  44.             PCROBOTS can only be run on a PC with an EGA or VGA monitor.
  45.  
  46.             A coprocessor is optional, but it will speed up processing
  47.             of functions like scans.
  48.  
  49.             PCROBOTS supports an Adlib compatible soundcard for (very)
  50.             basic sound effects.
  51.  
  52.  
  53.  
  54.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  55.             ============================================================
  56.  
  57.             How to run PCROBOTS
  58.             ~~~~~~~~~~~~~~~~~~~~
  59.  
  60.             To run the program, use a command line like:
  61.  
  62.             PCROBOTS robot1 robot1 robot2
  63.  
  64.             This will run the 'robot1' program twice, and the
  65.             'robot2' program once.
  66.  
  67.             You can also specify groups of robots to operate as teams.
  68.             To do this you use the name <team>.TM (eg 'myteam.tm')
  69.             instead of a robot name. This file should be a text file
  70.             with a separate line for each robot in the team.
  71.  
  72.             There are also optional parameters which can be used:
  73.  
  74.                  -d - this lets you run PCROBOTS in 'debugging' mode.
  75.                       Normally PCROBOTS will stop running as soon as
  76.                       there is only one robot left. Using this switch
  77.                       will make PCROBOTS keep running until you manually
  78.                       stop it by pressing the ESC key.
  79.  
  80.                  -l<n> - this lets you set the maximum number of 'ticks'
  81.                       that a game will run. A tick is not a fixed time
  82.                       interval, instead it is a complete turn for all
  83.                       the robots. There must not be a space between the
  84.                       'l' and the number to be used. Eg '-l5000' will
  85.                       run the game for 5000 ticks.
  86.  
  87.                  -f<name> - this will append a summary of the game
  88.                       results to the file specified after the 'f'. Again
  89.                       there must be no space between the 'f' and the
  90.                       filename which follows. If no filename is
  91.                       specified, then the name 'PCROBOTS.LOG' is used.
  92.  
  93.                  -s - this will run PCROBOTS in 'slow' mode to help you
  94.                       see what a robot is doing. Pressing the spacebar
  95.                       will toggle 'single step' mode on and off (the
  96.                       'enter' key will single step). Pressing the '0' to
  97.                       '9' keys will set the speed.
  98.  
  99.                  -q - this will run PCROBOTS in 'quick' mode. In this
  100.                       mode, certain features such as explosions, and
  101.                       sound effects are disabled to increase game speed.
  102.  
  103.                  -a - this allows you to specify an alternative arena
  104.                       file, rather than the default of PCROBOTS.RNA.
  105.  
  106.                  -m - this redirects STDOUT output to a monochrome
  107.                       monitor if you have one fitted to your PC (used
  108.                       for debugging robots).
  109.  
  110.  
  111.  
  112.  
  113.  
  114.             ============================================================
  115.                                                                Page No 2
  116.  
  117.  
  118.  
  119.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  120.             ============================================================
  121.  
  122.                  -v - this gives a 'verbose' output, both at startup,
  123.                       and in the results phase.
  124.  
  125.                  -r - this lets you set the random number generator seed
  126.                       to allow identical runs to be made.
  127.  
  128.             The parameters can be placed anywhere on the command line
  129.             following the PCROBOTS name.
  130.  
  131.             Errorlevel values
  132.             ~~~~~~~~~~~~~~~~~~
  133.             When PCRobots exits it sets the DOS errorlevel value to
  134.             allow testing from batch files. The values are:
  135.  
  136.              -1     = Error
  137.              0 -> n = Winning robot
  138.              100    = Draw (>=2 left alive)
  139.              101    = Draw (0 left alive)
  140.              200    = Esc pressed
  141.  
  142.             The PCROBOTS Arena
  143.             ~~~~~~~~~~~~~~~~~~~
  144.  
  145.             The 'Arena' is a large 1000x1000 area. Each robot can move a
  146.             maximum of 1 square per move. This is unlike the original
  147.             CROBOTS where a robot could move 100 square per move.
  148.  
  149.             The arena is displayed as a large white box occupying most
  150.             of the screen.Inside this box you will see any obstacles
  151.             that have been placed on the map (see later section for a
  152.             description of the map file). All obstacles have a white
  153.             border displayed around the square, and are defined as
  154.             below:
  155.                  White - A wall - Robots can see through this, but they
  156.                       can't move or fire shells through it. If a robot
  157.                       collides with a wall it will lose 1 armour point.
  158.                  Red - A damage trap - A robot loses 1 armour point for
  159.                       every turn it is on one of these squares.
  160.                  Green - A refueling point - If a robot comes to rest on
  161.                       one of these points, it will regain some battery
  162.                       power (see later section for more details). There
  163.                       can be up to 10 refueling points per arena.
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.             ============================================================
  180.                                                                Page No 3
  181.  
  182.  
  183.  
  184.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  185.             ============================================================
  186.  
  187.             The Robots
  188.             ~~~~~~~~~~~
  189.  
  190.             The robots will be displayed on the arena as small 5x5 pixel
  191.             shapes in a particular colour. The actual shape can be
  192.             defined in the robot program, but the default is a small
  193.             'smiley'.
  194.  
  195.             Down the right hand side of the screen there will be a list
  196.             of robots. For each entry down the right, the robot shape
  197.             and colour match the robot in the arena. Underneath the
  198.             robot are two bars. The top bar indicates the armour level
  199.             of the robot - the longer the bar the more armour there is
  200.             left, the shorter the bar, the more the robot is damaged.
  201.             The bottom bar indicates the battery level of the robot -
  202.             again, the longer the bar, the more battery power exists. A
  203.             rapidly moving robot will quickly exhaust its battery power,
  204.             meaning that it will have to wait a while until the battery
  205.             has been recharged slightly before moving on.
  206.  
  207.             If a robot has fired a cannon shell, this will be displayed
  208.             as a simple white pixel. Cannon shells move twice as fast as
  209.             the fastest robot can go, which is four times as fast as a
  210.             normal robot.
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.             ============================================================
  245.                                                                Page No 4
  246.  
  247.  
  248.  
  249.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  250.             ============================================================
  251.  
  252.             Teams
  253.             ~~~~~~~~~
  254.  
  255.             Starting with PCRobots V1.3, proper robot teams are
  256.             supported.
  257.  
  258.             Team starting locations are defined in the arena map - if a
  259.             starting location for a certain team isn't specified, then
  260.             the robots will be placed randomly.
  261.  
  262.             A team is a group of robots which the PCRobots kernel
  263.             recognises as being together. The robots have to work
  264.             together as well, as it's entirely possible for a team to
  265.             wipe itself out without any help from anyone else!
  266.  
  267.             To define a team you make a file with an extension .TM .
  268.             This file should contain a list of robot names with one name
  269.             per line.
  270.  
  271.             All the robots in a specified team will start in the map
  272.             square which is defined in the arena file. Their actual
  273.             positions on that map square are random.
  274.  
  275.             It is possible to mix teams and 'loners' on any run.
  276.  
  277.             Teams will be given a score after a run.
  278.  
  279.             The score is currently obtained from the number of robots
  280.             which are killed by that team.
  281.  
  282.                  100 points - enemy robot killed
  283.                 -500 points - friendly robot killed.
  284.  
  285.             Coordinates
  286.             ~~~~~~~~~~~~
  287.             The arena is defined with the coordinate 0,0 being at the
  288.             top left of the screen, and 999,999 being at the bottom
  289.             right of the screen.
  290.             Angles are defined as 0 degrees pointing to the right and
  291.             angles increase in a clockwise direction - so 90 degrees is
  292.             pointing straight down. (This allows the use of programs for
  293.             the original CRobots - the only difference being that 0,0 is
  294.             at the top left now, instead of the bottom right - this
  295.             means the robot will do a mirror image of its previous
  296.             action.
  297.  
  298.             The Map
  299.             ~~~~~~~~
  300.             The robot combat arena is defined in the file PCROBOTS.RNA
  301.             (if the file doesn't exist, then the arena is empty).
  302.  
  303.             The arena is divided into 10x10 pixel squares (that's
  304.             100x100 squares in the whole arena). The contents of each
  305.  
  306.  
  307.  
  308.  
  309.             ============================================================
  310.                                                                Page No 5
  311.  
  312.  
  313.  
  314.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  315.             ============================================================
  316.  
  317.             square are defined by a single character in the PCROBOTS.RNA
  318.             file.
  319.  
  320.             Each line of PCROBOTS.RNA defines a line in the arena, and
  321.             each character defines a square on that line.
  322.  
  323.             Ideally, a complete map will consist of 100 lines of 100
  324.             characters each. However, any lines which are not 100 lines
  325.             long will be assumed to be padded with empty area. If 100
  326.             lines don't exist, then the last lines will be padded with
  327.             empty area.
  328.  
  329.             The possible characters (at the moment) are:
  330.  
  331.              '.' - this is an empty square - internally has the value
  332.             set by 'ARENA_FREE' in pcrobots.h
  333.  
  334.              'X' - this is a wall - internally has the value set by
  335.             'ARENA_WALL' in pcrobots.h
  336.  
  337.              'D' - this is a damaging trap - internally has the value
  338.             set by 'ARENA_DAMAGE' in pcrobots.h
  339.  
  340.              'R' - this is a refueling point - internally has the value
  341.             set by 'ARENA_REFUEL' in pcrobots.h
  342.  
  343.              'A' -> 'C' - these are the starting positions for robot
  344.             teams A -> C. They are not marked on the maps.
  345.  
  346.             The robot's scanner will see straight through walls, so to
  347.             avoid collisions, the robot should periodically call
  348.             'get_local_map' to see a 9x9 area around the robot (this
  349.             will be quite a slow call, so shouldn't be called more than
  350.             necessary).
  351.  
  352.             Shells will not pass through walls, so although another
  353.             robot may see you hiding behind a wall, it will not be able
  354.             to damage you unless it moves around the wall. To see if a
  355.             shell has hit a wall you'll have to call the
  356.             'get_shell_status' routine, which will tell you if the last
  357.             shell to land hit a wall or a robot.
  358.  
  359.  
  360.             Robot Batteries
  361.             ~~~~~~~~~~~~~~~~
  362.             As of version 0.2 robots are powered by electrical
  363.             batteries.
  364.             These batteries are constantly being charged by a solar
  365.             panel, and are constantly being discharged by robot motion.
  366.  
  367.             The battery starts off being charged with 1000 units of
  368.             energy.
  369.             Each turn the battery will be charged by 4 units. Each turn
  370.             that the robot moves the battery will be discharged by the
  371.  
  372.  
  373.  
  374.             ============================================================
  375.                                                                Page No 6
  376.  
  377.  
  378.  
  379.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  380.             ============================================================
  381.  
  382.             current speed / 10. The battery can not be charged above the
  383.             1000 unit level.
  384.  
  385.             If the battery is flat, the robot will come to a
  386.             standstill,until the battery is charged again. This means
  387.             that the robot must issue a 'move' command to start the
  388.             robot moving again.
  389.  
  390.             Battery power may be traded to buy more shells, or more
  391.             armour.
  392.             Alternatively, armour may be traded to buy more battery
  393.             power.
  394.  
  395.             If a robot is destroyed, any battery power remaining is
  396.             transferred to the robot which dealt the death blow.
  397.  
  398.             Recharging Stations
  399.             ~~~~~~~~~~~~~~~~~~~~
  400.             A map may contain between 0 and 10 refueling stations where
  401.             robots can replenish their batteries.
  402.  
  403.             These refueling stations are simply large quick charging
  404.             batteries themselves. They recharge at a rate of 5 units per
  405.             turn, as long as no robot is currently being recharged from
  406.             them. Recharging units may not acquire more than 2000 units
  407.             of charge.
  408.  
  409.             A robot must be stationary and visible on a refueling
  410.             station in order to recharge its batteries. It will take 10
  411.             units of charge from the refueling station as long as there
  412.             is sufficient charge in the refueling station's batteries.
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.             ============================================================
  440.                                                                Page No 7
  441.  
  442.  
  443.  
  444.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  445.             ============================================================
  446.  
  447.             Robot Configuration
  448.             ~~~~~~~~~~~~~~~~~~~~
  449.  
  450.             Robots may now be customised to suit a specific task, you do
  451.             this by calling the configure routine, with the appropriate
  452.             parameters.
  453.  
  454.             The configuration call *must* be the first call in the
  455.             program. If you do not call it, all the parameters will be
  456.             set to their '2' value in the table below.
  457.  
  458.             Value  Speed Manouevre Range Armour Acceleration
  459.               0      50     20%     300     50      5
  460.               1      75     35%     500     75      7
  461.               2     100     50%     700    100     10
  462.               3     150     75%    1000    150     15
  463.               4     200    100%    1500    200     20
  464.  
  465.             You have a maximum of 10 points to allocate to the robot. If
  466.             you try to allocate more points to the robot, some items
  467.             will have a value of '0'.
  468.  
  469.             It is also possible to buy an 'invisibility' device using
  470.             this function. Normally a robot will start with 1000 shells
  471.             at the beginning of a game. If you take the invisibility
  472.             device this will be reduced to 900 shells.
  473.  
  474.             Invisibility
  475.             ~~~~~~~~~~~~~
  476.  
  477.             Invisibility is a purely defensive system, and will be of
  478.             negligible use in a 'dumb' robot.
  479.  
  480.             When your robot goes invisible it will be undetectable by
  481.             other robots' scanners, however, shells landing in the
  482.             vicinity will still damage the robot.
  483.  
  484.             Also, invisibility places the following limitations on your
  485.             robot:
  486.  
  487.                  - Scanning is not possible
  488.                  - Firing the cannon is not possible
  489.                  - The battery will *NOT* be recharged while invisible
  490.  
  491.             The main use of invisibility would be to hide while running
  492.             to a safer location (to stop some 'chase' robots from
  493.             following you there). When there it would be possible to
  494.             become visible to recharge the batteries.
  495.  
  496.             When the robot is invisible an 'I' will appear next to the
  497.             robot's name.
  498.  
  499.             A robot can only stay invisible for a maximum of 100 turns,
  500.             it will then automatically become visible again. After a
  501.  
  502.  
  503.  
  504.             ============================================================
  505.                                                                Page No 8
  506.  
  507.  
  508.  
  509.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  510.             ============================================================
  511.  
  512.             robot has become visible it must remain visible for as many
  513.             turns as it was invisible before it can turn invisible
  514.             again. Thus, if a robot was invisible for 50 turns, it must
  515.             be visible for at least 50 turns before it can go invisible
  516.             again.
  517.  
  518.             ROBOT DAMAGE
  519.             ~~~~~~~~~~~~~
  520.             When a robot collides with the outside of the arena, or is
  521.             hit by a shell then it is damaged. The values of damage are:
  522.  
  523.             Collision with edge of arena - 1 point
  524.             Explosion within 50 squares  - 2 points
  525.             Explosion within 25 squares  - 8 points
  526.             Explosion within 5 squares   - 25 points
  527.  
  528.             The explosion displayed on the screen has 3 coloured areas
  529.             corresponding to these radii: 50 squares is red, 25 squares
  530.             is yellow, and 5 squares is white.
  531.  
  532.             Debugging Aids
  533.             ~~~~~~~~~~~~~~~
  534.             There are several features to help you to debug robots.
  535.  
  536.             The most basic is the use of the 'debug flags'. These can
  537.             indicate certain 'modes' of operation of the robot, for
  538.             instance a robot may have a 'running' mode and an 'attack'
  539.             mode. A debug flag indicator could be used to let you see at
  540.             a glance which mode the robot is in.
  541.  
  542.             Writing to files is allowed during the debug stages of
  543.             writing a robot, but any code to do this should be removed
  544.             or disabled before allowing the robot out in public. Reading
  545.             from files is not allowed at any stage.
  546.  
  547.             It is also possible to send output to the 'stdout' file. In
  548.             C you do this by using any of the standard output routine
  549.             such as 'printf'. In Pascal you do it by using
  550.             WRITE/WRITELN, and in Assembler you simply send output to a
  551.             file with handle=1.
  552.  
  553.             This output will be ignored unless you give the '-s' or '-m'
  554.             options on the PCROBOTS command line.
  555.  
  556.             If you use '-m' the output will be displayed on an MDA
  557.             monitor attached to your PC in addition to the EGA/VGA
  558.             display. Don't use this option unless you have an MDA
  559.             adaptor fitted, as it may cause unpredictable results.
  560.  
  561.             If you use '-s' (without '-m') then the first 19 columns of
  562.             the output will be displayed in the right hand column of the
  563.             display (under the robot names and status indicators).
  564.  
  565.  
  566.  
  567.  
  568.  
  569.             ============================================================
  570.                                                                Page No 9
  571.  
  572.  
  573.  
  574.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  575.             ============================================================
  576.  
  577.             The output drivers understand certain special characters:
  578.  
  579.                  \n = 0ah = 10 - Line feed - the print position goes
  580.                       down a line
  581.                  \r = 0dh = 13 - Carriage Return - the print position
  582.                       goes to the left hand side of the current line
  583.                  \b = 08h = 8  - Backspace - the print position goes
  584.                       back one space
  585.                  \f = 0ch = 12 - Formfeed - the screen is cleared and
  586.                       the print position goes to the start of the screen
  587.                  <Esc>Y<y><x> - This is the VT52 cursor position code. y
  588.                       and x are specified by using the character which
  589.                       has the ASCII character of the required position
  590.                       plus 32. 1,1 is the top left of the screen. Thus
  591.                       <esc>Y!! will move the cursor to the top left of
  592.                       the screen.
  593.  
  594.             Most standard cursor positioning command will also work (for
  595.             instance 'gotoxy(x,y)' in Turbo C).
  596.  
  597.             Special Keys
  598.             ~~~~~~~~~~~~~
  599.             If during operation you wish to stop a game, pressing ESC
  600.             will cause it to stop at the next movement turn.
  601.  
  602.             Pressing Ctrl-Brk will cause all the robots to be killed
  603.             instantly (even if one of them is stuck in an internal
  604.             loop), and the program will exit.
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.             ============================================================
  635.                                                               Page No 10
  636.  
  637.  
  638.  
  639.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  640.             ============================================================
  641.  
  642.  
  643.             The ROBOT programs
  644.             ~~~~~~~~~~~~~~~~~~~
  645.             Each 'robot' program consists of a single .COM or small .EXE
  646.             file. These programs must obey certain rules for the program
  647.             to work correctly.
  648.  
  649.              - no standard I/O functions (such as printf) are allowed.
  650.  
  651.              - The program must *never* finish - the main program should
  652.             consist of an infinite loop. The PCRobots executive program
  653.             will kill the program when the robot is destroyed.
  654.  
  655.              - The program must not use any memory outside the 64k
  656.             segment which it is allocated.
  657.  
  658.              - The PSP is not completely created (and may be erroneous -
  659.             I have to create it in the PCRobots program, and it may not
  660.             match the proper definition - let me know if you find a
  661.             problem).
  662.              The sections which should be correct are:
  663.               - INT 20h
  664.               - Segment of end of allocation block
  665.               - Previous contents of ints 22,23,24
  666.               - Env block pointer (points to offset 0x90 of PSP which
  667.             contains a 00h,00h value).
  668.               - Command tail - contains 00h,0dh,00h.
  669.              The FCBs & Long call to function dispatcher aren't created.
  670.  
  671.              - Floating point maths are not allowed.
  672.  
  673.              - It must make sure that it always passes control back to
  674.             the executive program when it is idling.
  675.  
  676.             DOS Functions
  677.             ~~~~~~~~~~~~~~
  678.             In V1.3 a lot of DOS functions are disabled to prevent their
  679.             use in robot programs (using certain functions may be
  680.             construed as 'cheating').
  681.  
  682.             Basically all DOS functions will cause the robot to be
  683.             instantly killed, except for the following:
  684.  
  685.             AH=  9h - Display String (as normal)
  686.             AH= 25h - Set Int Vector (filtered)
  687.             AH= 2ah - Get date (as normal)
  688.             AH= 2bh - Set date (dummy - does nothing)
  689.             AH= 2ch - Get time (as normal)
  690.             AH= 2dh - Set time (dummy - does nothing)
  691.             AH= 30h - Get DOS Version (as normal)
  692.             AH= 35h - Get Int Vector (as normal)
  693.             AH= 3ch - Create file (as normal)
  694.             AH= 3eh - Close file (as normal)
  695.             AH= 40h - Write file or device (filtered)
  696.  
  697.  
  698.  
  699.             ============================================================
  700.                                                               Page No 11
  701.  
  702.  
  703.  
  704.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  705.             ============================================================
  706.  
  707.             AH= 43h - Get/Set file attributes (as normal)
  708.             AH= 44h - I/O Ctl (as normal)
  709.             AH= 45h - Duplicate handle (as normal)
  710.             AH= 46h - Force Duplicate handle (as normal)
  711.             AH= 4ah - Resize memory block (redefined)
  712.             AH= 59h - Get extended error info (as normal)
  713.             AH= 5ah - Create Temp file (as normal)
  714.             AH= 5bh - Create new file (as normal)
  715.  
  716.             Many of these are allowed so that compiler startup code can
  717.             operate properly.
  718.  
  719.             If you see a message such as
  720.             'killed by System Violation (4c00)' when PCRobots finishes,
  721.             then it means that a robot tried to call int 21h with AX set
  722.             to 4c00h.
  723.  
  724.             A couple of these functions are filtered or redefined. These
  725.             are:
  726.  
  727.             Set Int Vector
  728.             ===============
  729.             In this case all vector changes are ignored, except for
  730.             changes to int e0h (in which case the current robot is
  731.             instantly killed!), or int 34h -> int 3fh (in which case
  732.             alterations are made to a local interrupt vector table for
  733.             that task).
  734.  
  735.             Int e0h is also constantly being checked to prevent direct
  736.             tampering with the interrupt vector table.
  737.  
  738.             Write File or Device
  739.             =====================
  740.             Writes to stdout (file handle 1) are redirected to the
  741.             debugging output routines, other writes pass through as
  742.             normal.
  743.  
  744.             Resize Memory Block
  745.             ====================
  746.             DOS memory blocks are simulated by PCRobots to enforce a 64k
  747.             memory limit per robot. This is necessary for the EMS
  748.             operating mode.
  749.  
  750.             Robot Time Limit
  751.             ~~~~~~~~~~~~~~~~~
  752.             As of V1.3 a time limit is enforced for a move by a robot.
  753.             This time limit adjusts for the speed of the computer, and
  754.             should be around 3 seconds on a 33MHz 386.
  755.  
  756.             This time limit is not meant to seriously limit robots, it
  757.             is merely meant as a protection against robots getting stuck
  758.             in a loop like:
  759.  
  760.              do
  761.  
  762.  
  763.  
  764.             ============================================================
  765.                                                               Page No 12
  766.  
  767.  
  768.  
  769.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  770.             ============================================================
  771.  
  772.              {
  773.               getxy(&x,&y);
  774.              }
  775.              while (x>100);
  776.  
  777.             Special Functions
  778.             ~~~~~~~~~~~~~~~~~~
  779.             Special 'robot' functions such as movement, scanning,
  780.             statusreports etc, are accessed by using software interrupt
  781.             0E0h.
  782.  
  783.             The function number is placed in the AX register, and
  784.             anyrequired parameters are placed in the BX & CX registers.
  785.             Values are returned in these registers as appropriate.
  786.  
  787.             Function numbers less than 10h cause a task switch to occur.
  788.             This will end the current robot's 'turn' and give the next
  789.             robot a chance.
  790.  
  791.             There are several methods of using the special robot
  792.             functions. These are for Assembler language, C/C++, and
  793.             Turbo Pascal. There is a section on each of these below,
  794.             C/C++/Pascal are all included together as they are very
  795.             similar to use.
  796.  
  797.             C, C++ and Pascal Functions
  798.             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  799.  
  800.             For C and C++ there are two methods of using these
  801.             functions, via PCROBOTS.LIB or via PCROBOTS.OBJ.
  802.             PCROBOTS.LIB is a Borland Library, so it may not work with
  803.             non-Borland languages, whereas PCROBOTS.OBJ is a standard
  804.             .OBJ file, so it should work with any language which can
  805.             link an object file with the C parameter passing protocol.
  806.  
  807.             To use either of these routine you should
  808.             '#include "pcrobots.h" ' in your C/C++ program. The source
  809.             code for the library is supplied in PCROBOTS.C.
  810.  
  811.             For Turbo Pascal you can use the PCROBOTS.TPU unit. This was
  812.             compiled with Turbo Pascal V5.5, but it should work with
  813.             other versions of Turbo Pascal.
  814.  
  815.             Add 'uses pcrobots;' to your source code.
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.             ============================================================
  830.                                                               Page No 13
  831.  
  832.  
  833.  
  834.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  835.             ============================================================
  836.  
  837.             Function names
  838.             ~~~~~~~~~~~~~~~
  839.  
  840.             void swaptask(void);
  841.             procedure swaptask;
  842.             ====================
  843.  
  844.                  This procedure will simply end the current robot's turn
  845.                  if it has nothing else to do. Use this if, for
  846.                  instance, you're waiting for the robot to move to a
  847.                  certain location.
  848.  
  849.             void movement(int speed, int angle);
  850.             procedure movement(speed,angle:integer);
  851.             ========================================
  852.  
  853.                  This procedure will cause the robot to start moving in
  854.                  the specified direction at the specified speed.
  855.  
  856.                  speed = 0 - max speed of robot (<=200)
  857.                  angle = 0 - 359 degrees
  858.  
  859.                  The speed will change to the target speed at the
  860.                  maximum acceleration rate specified for this robot.
  861.  
  862.                  If the robot is going above its manouvrability speed,
  863.                  then it will not be able to change direction. It must
  864.                  slow down first.
  865.  
  866.                  This procedure will cause the current robot's turn to
  867.                  end.
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.             ============================================================
  895.                                                               Page No 14
  896.  
  897.  
  898.  
  899.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  900.             ============================================================
  901.  
  902.             int scan(int angle,int res,int *range);
  903.             Function scan(angle,res:integer;var range:integer):integer;
  904.             ===========================================================
  905.  
  906.                  This function will cause the robot to scan for other
  907.                  robots in the specified direction.
  908.  
  909.                  angle = 0 - 359 degrees
  910.                  res   = 0 - 45 degrees
  911.  
  912.                  returns the id number of the robot which was detected,
  913.                  or -1 if no robot was detected.
  914.  
  915.                  The range value is set to the range to the detected
  916.                  robot, if no robot was detected, the range is
  917.                  unspecified.
  918.  
  919.                  The scan function will scan along a specified direction
  920.                  with the specified resolution. For instance a
  921.                  scan(300,5,....) will look at the angles from 295
  922.                  degrees to 305 degrees.
  923.  
  924.                  This function will cause the current robot's turn to
  925.                  end.
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.             ============================================================
  960.                                                               Page No 15
  961.  
  962.  
  963.  
  964.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  965.             ============================================================
  966.  
  967.             int shoot(int angle,int range);
  968.             Function shoot(angle,range:integer):integer;
  969.             ============================================
  970.  
  971.                  This function causes the robot to fire a shell in the
  972.                  specified direction for the specified range. The shell
  973.                  will be fired into the air, so it will not hit any
  974.                  targets before the range is reached.
  975.  
  976.                  angle = 0 - 359 degrees
  977.                  range = 0 - max range of robot's cannon
  978.  
  979.                  if the robot was able to fire a shell then the function
  980.                  will return 1, if it was unable to fire a shell for any
  981.                  reason, then it will return 0.
  982.  
  983.                  The robot's turret is independant of the robot's
  984.                  heading, so shells can be fired in any direction.
  985.  
  986.                  Seven shells per robot are allowed in the air at once.
  987.                  Also, the cannon takes 50 ticks to reload.
  988.  
  989.                  The robot normally starts with only 1000 shells, if
  990.                  these all run out (very unusual!), then the robot will
  991.                  be unable to fire its cannon, unless it purchases more
  992.                  shells (see 'buy_shells' function).
  993.  
  994.                  This function will cause the current robot's turn to
  995.                  end.
  996.  
  997.             void get_remote_map(char far *buffer,int x,int y);
  998.             procedure get_remote_map(ptr:MapBuf_ptr;x,y:integer);
  999.             ========================================
  1000.  
  1001.                  This procedure lets you obtain a map of any area of the
  1002.                  map. This function is similar to 'get_local_map', but
  1003.                  the x and y coordinates of the map centre can be
  1004.                  arbitrarily specified.
  1005.  
  1006.                  x and y are values 0-99 as they specify the position on
  1007.                  the map, not on the arena.
  1008.  
  1009.  
  1010.             void getxy(int near *x,int near *y);
  1011.             procedure getxy(var x,y:integer);
  1012.             =================================
  1013.  
  1014.                  This function will return the current position of the
  1015.                  robot.
  1016.  
  1017.                  The x and y coordinates of the robots are returned in
  1018.                  the x and y parameters (possible values are 0 - 999).
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.             ============================================================
  1025.                                                               Page No 16
  1026.  
  1027.  
  1028.  
  1029.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1030.             ============================================================
  1031.  
  1032.             int transmit(int target,int data);
  1033.             function transmit(target,data:integer):integer;
  1034.             ===============================================
  1035.  
  1036.                  This function will transmit the specified data to the
  1037.                  specified robot.
  1038.  
  1039.                  target = target robot id - as obtained from the scan
  1040.                            function.
  1041.                  data   = data word to send to the robot.
  1042.  
  1043.                  If the data could not be sent for any reason, the
  1044.                  function will return 0, otherwise it will return 1.
  1045.  
  1046.                  It costs one battery unit to transmit a word of data.
  1047.  
  1048.                  Robots have a 20 word FIFO receive queue where received
  1049.                  data is stored until it is read. If this buffer is
  1050.                  full, or the target robot does not exist, then this
  1051.                  function will return a 0. Success of the call does
  1052.                  *not* mean that the target robot has actually looked at
  1053.                  the received data.
  1054.  
  1055.             int receive(int *source,int *data);
  1056.             function receive(var source,data:integer):integer;
  1057.             ==================================================
  1058.  
  1059.                  This function allows a robot to see if any data has
  1060.                  been sent to it by another robot.
  1061.  
  1062.                  The function will return 1 if data exists, or 0 if the
  1063.                  receive buffer is empty.
  1064.  
  1065.                  If data exists, then source will be set to the id
  1066.                  number of the sending robot, and data will be set to
  1067.                  the data which was sent.
  1068.  
  1069.                  If the receive buffer was empty, then source and data
  1070.                  will be undefined.
  1071.  
  1072.                  Because this function does not cause the current
  1073.                  robot's turn to end, it is recommended that this
  1074.                  function is called periodicallyto clear up the robot's
  1075.                  input buffer, even if the data is subsequently ignored.
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.             ============================================================
  1090.                                                               Page No 17
  1091.  
  1092.  
  1093.  
  1094.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1095.             ============================================================
  1096.  
  1097.             int damage(void);
  1098.             function damage:integer;
  1099.             ========================
  1100.  
  1101.                  This function will return the current damage status of
  1102.                  the robot.
  1103.  
  1104.                  The lower the value, the more damaged the robot is. The
  1105.                  initial value depends on the robot's configuration, but
  1106.                  is normally 100.
  1107.  
  1108.             int speed(void);
  1109.             function speed:integer;
  1110.             =======================
  1111.  
  1112.                  This function will return the current speed of the
  1113.                  robot.
  1114.  
  1115.  
  1116.             int battery(void);
  1117.             function battery:integer;
  1118.             =========================
  1119.  
  1120.                  This function will return the current status of the
  1121.                  battery.
  1122.  
  1123.             long ticks(void);
  1124.             function ticks:longint;
  1125.             =======================
  1126.  
  1127.                  This function will return the number of game ticks
  1128.                  since the beginning of the game. This is not related to
  1129.                  real time, just the number of complete turns that have
  1130.                  elapsed.
  1131.  
  1132.             long l_sin(int angle);
  1133.             function l_sin(angle:integer):longint;
  1134.             ======================================
  1135.  
  1136.                  This function will return the sine of the requested
  1137.                  angle, scaled up by a factor of 100,000.
  1138.  
  1139.                  angle = 0 - 359
  1140.  
  1141.                  This function is supported because it is not advisable
  1142.                  to use floating point numbers in the robot programs.
  1143.                  Scaled integer values should be used instead.
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.             ============================================================
  1155.                                                               Page No 18
  1156.  
  1157.  
  1158.  
  1159.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1160.             ============================================================
  1161.  
  1162.             long l_cos(int angle);
  1163.             function l_cos(angle:integer):longint;
  1164.             ======================================
  1165.  
  1166.                  This function will return the cosine of the requested
  1167.                  angle, scaled up by a factor of 100,000.
  1168.  
  1169.                  angle = 0 - 359
  1170.  
  1171.                  This function is supported because it is not advisable
  1172.                  to use floating point numbers in the robot programs.
  1173.                  Scaled integer values should be used instead.
  1174.  
  1175.             long l_tan(int angle);
  1176.             function l_tan(angle:integer):longint;
  1177.             ======================================
  1178.  
  1179.                  This function will return the tangent of the requested
  1180.                  angle, scaled up by a factor of 100,000.
  1181.  
  1182.                  angle = 0 - 359
  1183.  
  1184.                  This function is supported because it is not advisable
  1185.                  to use floating point numbers in the robot programs.
  1186.                  Scaled integer values should be used instead.
  1187.  
  1188.             int l_atan(long ratio);
  1189.             function l_atan(ratio:longint):integer;
  1190.             =======================================
  1191.  
  1192.                  This function will return the arctangent of the
  1193.                  requested value.
  1194.  
  1195.                  The value should be scaled up by 100,000 times.
  1196.  
  1197.                  The return value is the angle in the range -90 degrees
  1198.                  to +90 degrees.
  1199.  
  1200.             long l_sqrt(long square);
  1201.             function l_sqrt(square:longint):longint;
  1202.             ========================================
  1203.  
  1204.                  This function will return the square root of a number.
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.             ============================================================
  1220.                                                               Page No 19
  1221.  
  1222.  
  1223.  
  1224.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1225.             ============================================================
  1226.  
  1227.  
  1228.             void set_pattern(const char far *pattern);
  1229.             procedure set_pattern(Buffer:Patbuf_ptr);
  1230.             ==========================================
  1231.  
  1232.                  This procedure will set the current pattern used to
  1233.                  draw the robot on the display.
  1234.  
  1235.                  C/C++
  1236.                  ======
  1237.                  The pattern array should consist of 5 bytes. The lower
  1238.                  5 bits of each byte will be used as a bit pattern for
  1239.                  the appropriate line of the robot's icon.
  1240.  
  1241.                  PASCAL
  1242.                  =======
  1243.  
  1244.                  There are 2 type definitions:
  1245.  
  1246.                  Pattern_buffer=array[0..5] of shortint;
  1247.                  Patbuf_ptr=^Pattern_buffer;
  1248.  
  1249.                  Pattern_buffer should be filled with 5 bytes. The lower
  1250.                  5 bits of each byte will be used as a bit pattern for
  1251.                  the appropriate line of the robot's icon.
  1252.  
  1253.                  The pointer value of this array should be used as the
  1254.                  parameter to the procedure call.
  1255.  
  1256.             void debug_flag(int flag_no,int flag_set);
  1257.             procedure debug_flag(flag_no,flag_set:integer);
  1258.             ===============================================
  1259.  
  1260.                  This procedure allows you to set or clear two flag
  1261.                  markers by the side of the robot's name down the right
  1262.                  hand side of the screen.
  1263.  
  1264.                  flag_no = 0 or 1
  1265.                  flag_set= 0 or 1
  1266.  
  1267.                  These two flags may be used for whatever purpose you
  1268.                  want, but they are often useful for debugging purposes.
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.             ============================================================
  1285.                                                               Page No 20
  1286.  
  1287.  
  1288.  
  1289.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1290.             ============================================================
  1291.  
  1292.             void buy_armour(int units);
  1293.             procedure buy_armour(units:integer);
  1294.             ====================================
  1295.  
  1296.                  This procedure lets your robot buy or sell armour.
  1297.  
  1298.                  units = number of units to buy.
  1299.  
  1300.                  If 'units' is negative, then armour will be sold.
  1301.  
  1302.                  Armour units currently are worth 50 battery units, so
  1303.                  if a robot has a high battery charge it is possible to
  1304.                  sell some units to repair damaged armour. Also, if a
  1305.                  robot needs some battery power, it can sell armour in
  1306.                  exchange for some more battery power.
  1307.  
  1308.                  The armour rating can not go above the robot's initial
  1309.                  armour rating, any extra purchased units will be
  1310.                  wasted.
  1311.  
  1312.                  NB. It is quite possible to commit suicide using this
  1313.                  call.
  1314.  
  1315.  
  1316.             void buy_shells(unsigned int units);
  1317.             procedure buy_shells(units:word);
  1318.             ====================================
  1319.  
  1320.                  This procedure lets you purchase more cannon shells.
  1321.  
  1322.                  units = number of shells to buy.
  1323.  
  1324.                  It is not possible to sell shells in exchange for
  1325.                  battery power. Shells cost 10 battery units each.
  1326.  
  1327.             int shells_left(void);
  1328.             function shells_left:integer;
  1329.             =============================
  1330.  
  1331.                  This function lets your robot determine how many cannon
  1332.                  shells it has remaining.
  1333.  
  1334.                  Returns the number of shells remaining.
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.             ============================================================
  1350.                                                               Page No 21
  1351.  
  1352.  
  1353.  
  1354.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1355.             ============================================================
  1356.  
  1357.             void get_local_map(char far *buffer);
  1358.             procedure get_local_map(ptr:MapBuf_ptr);
  1359.             ========================================
  1360.  
  1361.                  This procedure lets you obtain a map of the area local
  1362.                  to the robot. You will receive a 9x9 square map of the
  1363.                  local area, the robot's current position will be in the
  1364.                  centre square of the map. See the section on the map
  1365.                  for details of the contents of the map.
  1366.  
  1367.                  C/C++
  1368.                  ======
  1369.                  The map array should be 81 bytes long.
  1370.  
  1371.                  PASCAL
  1372.                  =======
  1373.  
  1374.                  There are 2 type definitions:
  1375.  
  1376.                  Map_buffer=array[0..8,0..8] of shortint;
  1377.                  Mapbuf_ptr=^Map_buffer;
  1378.  
  1379.                  Pass the pointer to a type of Map_buffer to the
  1380.                  procedure.
  1381.  
  1382.             void invisibility(int invis_flag);
  1383.             procedure invisibility(invis_flag:integer);
  1384.             ===========================================
  1385.  
  1386.                  This procedure allow the robot to become invisible or
  1387.                  visible.
  1388.  
  1389.                  invis_flag = 0 - robot is visible,
  1390.                             = 1 - robot is invisible.
  1391.  
  1392.                  If the robot isn't capable of becoming invisible, then
  1393.                  this procedure will do nothing.
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.             ============================================================
  1415.                                                               Page No 22
  1416.  
  1417.  
  1418.  
  1419.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1420.             ============================================================
  1421.  
  1422.             int get_shell_status(void);
  1423.             function get_shell_status:integer;
  1424.             ==================================
  1425.  
  1426.                  This function will return a status value reporting what
  1427.                  happened to the last shell to land.
  1428.  
  1429.                  Return value:  0 - shell missed totally
  1430.                                 1 - shell hit a wall
  1431.                                 2 - shell hit a robot within a 50 square
  1432.                                      radius
  1433.                                 3 - shell hit a robot within a 25 square
  1434.                                      radius
  1435.                                 4 - shell hit a robot within a 5 square
  1436.                                      radius
  1437.  
  1438.                  This can be useful to see if a shell is firing at a
  1439.                  robot which is hiding behind a wall.
  1440.  
  1441.             int isinvisible(void);
  1442.             function isinvisible:integer;
  1443.             =============================
  1444.  
  1445.                  This function will return a flag indicating whether the
  1446.                  robot is invisible or not.
  1447.  
  1448.                  Return value:  0 - robot is visible,
  1449.                                 1 - robot is invisible.
  1450.  
  1451.             int atan2(int y,int x);
  1452.             function atan2(y,x:integer):integer;
  1453.             ====================================
  1454.  
  1455.                  This function will return the arctangent of y/x, giving
  1456.                  the correct value even if x is near 0. If both x and y
  1457.                  are 0, then this function will return 0.
  1458.  
  1459.             int get_robot_id(void);
  1460.             function get_robot_id:integer;
  1461.             ==============================
  1462.  
  1463.                  This function will return the robot ID of the current
  1464.                  robot.
  1465.  
  1466.             void register_iff(char far *iff_string);
  1467.             =============================================
  1468.  
  1469.                  This function will inform PCRobots of the 'IFF' string
  1470.                  for this particular robot. The IFF string may only be
  1471.                  set once.
  1472.  
  1473.                  The 'iff_string' parameter is a C format zero-
  1474.                  terminated string.
  1475.  
  1476.  
  1477.  
  1478.  
  1479.             ============================================================
  1480.                                                               Page No 23
  1481.  
  1482.  
  1483.  
  1484.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1485.             ============================================================
  1486.  
  1487.             int check_iff(int id);
  1488.             function check_iff(id:integer):integer;
  1489.             =======================================
  1490.  
  1491.                  This function will check to see if the robot with id
  1492.                  'id' has the same 'IFF' string as the current robot. It
  1493.                  will return 1 if the strings match, or 0 otherwise.
  1494.  
  1495.             void register_name(char far *name_string);
  1496.             ==============================================
  1497.  
  1498.                  This function will inform PCRobots of the name of this
  1499.                  robot. The name may only be set once.
  1500.  
  1501.                  The 'name_string' parameter is a C format zero-
  1502.                  terminated string.
  1503.  
  1504.             int find_name(int id,char far *name_string);
  1505.             ================================================
  1506.  
  1507.                  This function will search for a specified name. The
  1508.                  search will start at 'id' and end when there are no
  1509.                  more robots to check.
  1510.  
  1511.                  If no robot is found, it will return -1, otherwise it
  1512.                  will return the robot id.
  1513.  
  1514.                  The 'name_string' parameter is a C format zero-
  1515.                  terminated string.
  1516.  
  1517.             int get_team_id(void);
  1518.             function get_team_id:integer;
  1519.             =============================
  1520.  
  1521.                  This function will return the team which the current
  1522.                  robot is on. -1 will be returned if it is a 'loner',
  1523.                  otherwise the team number (0-2) will be returned.
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.             ============================================================
  1545.                                                               Page No 24
  1546.  
  1547.  
  1548.  
  1549.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1550.             ============================================================
  1551.  
  1552.             int configure(int speed,int manouevre,int range,int
  1553.                            armour,int acceleration,int invisibility);
  1554.             function configure(speed,manouevre,range, armour,
  1555.                            acceleration,invisibility:integer):integer;
  1556.             ==========================================================
  1557.  
  1558.                  This function allows you to configure the robot to suit
  1559.                  the program. It *must* be called as the first thing in
  1560.                  the program.
  1561.  
  1562.                  For values of the parameters, look at the 'robot
  1563.                  configuration' section.
  1564.  
  1565.                  This function returns 0 if it was not the first
  1566.                  PCRobots call in the program (in which case it was
  1567.                  ignored).
  1568.  
  1569.                  If this function was called as the first thing in the
  1570.                  program, then it will return the PCRobots version
  1571.                  number in the two bytes of the return value. The high
  1572.                  byte will be the 'major' version number, and the low
  1573.                  byte will be the 'minor' version number. For instance
  1574.                  V1.30 will return 0x0130.
  1575.  
  1576.  
  1577.  
  1578.             Assembler functions
  1579.             ~~~~~~~~~~~~~~~~~~~~
  1580.  
  1581.             An 8086 assembler program will normally call the functions
  1582.             directly, via an INT 0E0h software interrupt.
  1583.  
  1584.             The details below specify what parameters to place in which
  1585.             registers, and what the returned values are.
  1586.  
  1587.             Look at the C/C++ and Pascal functions above for
  1588.             descriptions of the functions themselves.
  1589.  
  1590.             The PCROBOTS.INC file may be used to specify the values to
  1591.             place in AX.
  1592.  
  1593.             SWAPTASK
  1594.             ========
  1595.  
  1596.             Call with:     AX = 00
  1597.  
  1598.             MOVEMENT
  1599.             ========
  1600.  
  1601.             Call with:     AX = 01
  1602.                            BX = speed 0-100
  1603.                            CX = direction 0-359
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.             ============================================================
  1610.                                                               Page No 25
  1611.  
  1612.  
  1613.  
  1614.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1615.             ============================================================
  1616.  
  1617.             SCAN
  1618.             =====
  1619.  
  1620.             Call with:     AX = 02
  1621.                            BX = direction 0-359 degrees
  1622.                            CX = resolution 0-45 degrees
  1623.  
  1624.             Returns value  AX = -1 if nothing detected
  1625.                               = robot id if a robot is detected
  1626.                                 (robot id's are 0-19)
  1627.                            BX = range to the detected robot.
  1628.  
  1629.             SHOOT
  1630.             ======
  1631.  
  1632.             Call with:     AX = 03
  1633.                            BX = direction 0-359
  1634.                            CX = range 0-700
  1635.  
  1636.             Returns value in AX = 1 if shell fired, 0 otherwise.
  1637.             GET REMOTE MAP
  1638.             ==============
  1639.  
  1640.             Call with:     AX = 21h
  1641.                            BX = segment of map buffer
  1642.                            CX = offset of map buffer
  1643.                            DH = x of map centre
  1644.                            DL = y of map centre
  1645.  
  1646.                  The map buffer must be at least 81 bytes long, and will
  1647.                  be filled with a 9x9 area of the map, with the
  1648.                  specified position in the centre.
  1649.  
  1650.             GETXY
  1651.             ======
  1652.  
  1653.             Call with:     AX = 10h
  1654.  
  1655.             Returns values BX = Current X coordinate (0-999)
  1656.                            CX = Current Y coordinate (0-999)
  1657.  
  1658.             TRANSMIT
  1659.             =========
  1660.  
  1661.             Call with:     AX = 11h
  1662.                            BX = target robot ID
  1663.                            CX = data to be sent
  1664.  
  1665.             Returns value  AX = 0 if data could not be sent,
  1666.                               = 1 otherwise.
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.             ============================================================
  1675.                                                               Page No 26
  1676.  
  1677.  
  1678.  
  1679.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1680.             ============================================================
  1681.  
  1682.             RECEIVE
  1683.             ========
  1684.  
  1685.             Call with:     AX = 12h
  1686.  
  1687.             Returns values AX = 1 if data exists,
  1688.                               = 0 if the buffer is empty
  1689.                  If AX=1
  1690.                            BX = sender's ID ('reply to' address)
  1691.                            CX = data
  1692.  
  1693.             DAMAGE
  1694.             =======
  1695.  
  1696.             Call with:     AX = 13h
  1697.  
  1698.             Returns value  BX = damage status
  1699.  
  1700.             SPEED
  1701.             ======
  1702.  
  1703.             Call with:     AX = 14h
  1704.  
  1705.             Returns value  BX = current speed
  1706.  
  1707.             BATTERY
  1708.             ========
  1709.  
  1710.             Call with:     AX = 15h
  1711.  
  1712.             Returns value  BX = battery charge
  1713.  
  1714.             TICKS
  1715.             ======
  1716.  
  1717.             Call with:     AX = 16h
  1718.  
  1719.             Returns value  BX = Most significant 16 bits
  1720.                            CX = Least significant 16 bits
  1721.  
  1722.             SIN
  1723.             ====
  1724.  
  1725.             Call with:     AX = 17h
  1726.                            BX = angle (0-359 degrees)
  1727.  
  1728.             Returns value of 100,000 x the sine of the angle
  1729.                            BX = Most significant 16 bits
  1730.                            CX = Least significant 16 bits
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.             ============================================================
  1740.                                                               Page No 27
  1741.  
  1742.  
  1743.  
  1744.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1745.             ============================================================
  1746.  
  1747.             COS
  1748.             ====
  1749.  
  1750.             Call with:     AX = 18h
  1751.                            BX = angle (0-359 degrees)
  1752.  
  1753.             Returns value of 100,000 x the cosine of the angle
  1754.                            BX = Most significant 16 bits
  1755.                            CX = Least significant 16 bits
  1756.  
  1757.             TAN
  1758.             ====
  1759.  
  1760.             Call with:     AX = 19h
  1761.                            BX = angle (0-359 degrees)
  1762.  
  1763.             Returns value of 100,000 x the tangent of the angle
  1764.                            BX = Most significant 16 bits
  1765.                            CX = Least significant 16 bits
  1766.  
  1767.             ATAN
  1768.             =====
  1769.  
  1770.             Call with:     AX = 1Ah
  1771.                            BX = Most significant 16 bits
  1772.                            CX = Least significant 16 bits
  1773.  
  1774.             Returns value  AX = angle (-90 to +90 degrees)
  1775.  
  1776.                  The BX,CX parameters make up a 32 bit value that is
  1777.                  scaled up by 100,000. Hence a BX,CX of 100,000 will
  1778.                  return an angle of 45 degrees.
  1779.  
  1780.             SQRT
  1781.             =====
  1782.  
  1783.             Call with:     AX = 1Bh
  1784.                            BX = Most significant 16 bits of value
  1785.                            CX = Least significant 16 bits of value
  1786.  
  1787.             Returns value  BX = Most significant 16 bits of square root
  1788.                            CX = Least significant 16 bits
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.             ============================================================
  1805.                                                               Page No 28
  1806.  
  1807.  
  1808.  
  1809.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1810.             ============================================================
  1811.  
  1812.             SET_PATTERN
  1813.             ============
  1814.             his call will change the robot's displayed picture.
  1815.  
  1816.             Call with:     AX = 1Ch
  1817.                            BX = segment of pattern array
  1818.                            CX = offset of pattern array
  1819.  
  1820.             The pattern array should consist of 5 bytes. The lower 5
  1821.             bits of each byte are used as a bit pattern for the
  1822.             appropriate line of the robot's picture.
  1823.  
  1824.  
  1825.             DEBUG_FLAG
  1826.             ===========
  1827.  
  1828.             Call with:     AX = 1Dh
  1829.                            BX = flag number to set (0 or 1)
  1830.                            CX = set/reset flag (0=reset, 1=set)
  1831.  
  1832.             BUY ARMOUR
  1833.             ===========
  1834.  
  1835.             Call with:     AX = 1Eh
  1836.                            BX = number of armour units to buy.
  1837.  
  1838.             BUY SHELLS
  1839.             ===========
  1840.  
  1841.             Call with:     AX = 1Fh
  1842.                            BX = number of shells to buy
  1843.  
  1844.             SHELLS LEFT
  1845.             ============
  1846.  
  1847.             Call with:     AX = 20h
  1848.  
  1849.             Returns value  BX = number of shells remaining
  1850.  
  1851.             GET LOCAL MAP
  1852.             ==============
  1853.  
  1854.             Call with:     AX = 21h
  1855.                            BX = segment of map buffer
  1856.                            CX = offset of map buffer
  1857.  
  1858.                  The map buffer must be at least 81 bytes long, and will
  1859.                  be filled with a 9x9 area of the map, with the robot's
  1860.                  position in the centre.
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.             ============================================================
  1870.                                                               Page No 29
  1871.  
  1872.  
  1873.  
  1874.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1875.             ============================================================
  1876.  
  1877.             INVISIBILITY
  1878.             =============
  1879.  
  1880.             Call with:     AX = 22h
  1881.                            BX = 0 - become visible
  1882.                               = 1 - become invisible
  1883.  
  1884.              GET SHELL STATUS
  1885.             ==================
  1886.  
  1887.             Call with:     AX = 23h
  1888.  
  1889.             Returns value  BX = 0 - shell missed totally
  1890.                                 1 - shell hit a wall
  1891.                                 2 - shell hit a robot within a 50 square
  1892.                                      radius
  1893.                                 3 - shell hit a robot within a 25 square
  1894.                                      radius
  1895.                                 4 - shell hit a robot within a 5 square
  1896.                                      radius
  1897.  
  1898.             IS INVISIBLE
  1899.             =============
  1900.  
  1901.             Call with:     AX = 24h
  1902.  
  1903.             Returns value  BX = 0 - robot is visible
  1904.                                 1 - robot is invisible
  1905.  
  1906.             ATAN2
  1907.             =====
  1908.  
  1909.             Call with:     AX = 25h
  1910.                            BX = y
  1911.                            CX = x
  1912.  
  1913.             Returns value  AX = angle - arctangent of y/x.
  1914.  
  1915.             GET_ROBOT_ID
  1916.             =============
  1917.  
  1918.             Call with:     AX = 26h
  1919.  
  1920.             Returns value  AX = robot id
  1921.  
  1922.             REGISTER_IFF
  1923.             =============
  1924.  
  1925.             Call with:     AX = 27h
  1926.                            BX = segment of iff_string
  1927.                            CX = offset of iff_string
  1928.                                 (string is zero terminated)
  1929.  
  1930.             CHECK_IFF
  1931.  
  1932.  
  1933.  
  1934.             ============================================================
  1935.                                                               Page No 30
  1936.  
  1937.  
  1938.  
  1939.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  1940.             ============================================================
  1941.  
  1942.             ==========
  1943.  
  1944.             Call with:     AX = 28h
  1945.                            BX = Robot Id to test
  1946.  
  1947.             Returns value  AX = 1 - IFF strings match
  1948.                                 0 - IFF strings don't match (or invalid
  1949.                                      robot ID)
  1950.  
  1951.             REGISTER_NAME
  1952.             ==============
  1953.  
  1954.             Call with:     AX = 29h
  1955.                            BX = segment of name_string
  1956.                            CX = offset of name_string
  1957.                                 (string is zero terminated)
  1958.  
  1959.             FIND_NAME
  1960.             ==========
  1961.  
  1962.             Call with:     AX = 2Ah
  1963.                            BX = segment of name_string
  1964.                            CX = offset of name_string
  1965.                                 (string is zero terminated)
  1966.                            DX = Start ID
  1967.  
  1968.             Returns value  AX = Found Robot ID (-1 if no robot with that
  1969.                                 name)
  1970.  
  1971.             GET_TEAM_ID
  1972.             ============
  1973.  
  1974.             Call with:     AX = 2Bh
  1975.  
  1976.             Returns value  AX = Team ID value (0-2) or -1 if a 'loner'.
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.  
  1991.  
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.             ============================================================
  2000.                                                               Page No 31
  2001.  
  2002.  
  2003.  
  2004.             PCROBOTS V1.3 - P.D.Smith 29 October, 1992
  2005.             ============================================================
  2006.  
  2007.             CONFIGURE
  2008.             ==========
  2009.  
  2010.             Call with:     AX = 80h
  2011.                            BX,CX = configuration details:
  2012.  
  2013.                            BX bits    0-3  = max speed
  2014.                                       4-7  = manouevrability
  2015.                                       8-11 = cannon range
  2016.                                      12-15 = robot armour
  2017.  
  2018.                            CX bits   0-2   = robot acceleration
  2019.                                      3     = invisiblity capability
  2020.  
  2021.             Returns value  AX = 1 - Configuration OK
  2022.                               = 0 - Call was not first thing in program
  2023.  
  2024.             Values of BX,CX bitmapped values:
  2025.  
  2026.             Value  Speed Manouevre Range Armour Acceleration
  2027.               0      50     20%     300     50      5
  2028.               1      75     35%     500     75      7
  2029.               2     100     50%     700    100     10
  2030.               3     150     75%    1000    150     15
  2031.               4     200    100%    1500    200     20
  2032.  
  2033.                  You have a maximum of 10 points to allocate to the
  2034.                  robot. If you try to allocate more points to the robot,
  2035.                  some items will have a value of '0'.
  2036.  
  2037.  
  2038.  
  2039.             ============================================================
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.             ============================================================
  2065.                                                               Page No 32
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.             Introduction                                 1
  2074.  
  2075.             Hardware Requirements                               1
  2076.  
  2077.             How to run PCROBOTS                                 2
  2078.                  -d command line option                         2
  2079.                  -l command line option                         2
  2080.                  -f command line option                         2
  2081.                  -s command line option                         2
  2082.                  -q command line option                         2
  2083.                  -a command line option                         2
  2084.                  -m command line option                         2
  2085.                  -v command line option                         3
  2086.                  -r command line option                         3
  2087.  
  2088.             Errorlevel values                                   3
  2089.  
  2090.             The PCROBOTS Arena                                  3
  2091.  
  2092.             The Robots                                          4
  2093.  
  2094.             Teams                                               5
  2095.  
  2096.             Coordinates                                         5
  2097.  
  2098.             The Map                                             5
  2099.  
  2100.             Robot Batteries                                     6
  2101.  
  2102.             Recharging Stations                                 7
  2103.  
  2104.             Robot Configuration                                 8
  2105.  
  2106.             Invisibility                                        8
  2107.  
  2108.             ROBOT DAMAGE                                        9
  2109.  
  2110.             Debugging Aids                                      9
  2111.  
  2112.             Special Keys                                       10
  2113.  
  2114.             The ROBOT programs                                 11
  2115.  
  2116.             DOS Functions                                      11
  2117.  
  2118.             Robot Time Limit                                   12
  2119.  
  2120.             Special Functions                                  13
  2121.  
  2122.             C, C++ and Pascal Functions                        13
  2123.  
  2124.             Function names                                     14
  2125.                  swaptask                                      14
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.                  movement                                      14
  2133.                  scan                                          15
  2134.                  shoot                                         16
  2135.                  getxy                                         16
  2136.                  transmit                                      17
  2137.                  receive                                       17
  2138.                  damage                                        18
  2139.                  speed                                         18
  2140.                  battery                                       18
  2141.                  ticks                                         18
  2142.                  l_sin                                         18
  2143.                  l_cos                                         19
  2144.                  l_tan                                         19
  2145.                  l_atan                                        19
  2146.                  l_sqrt                                        19
  2147.                  set_pattern                                   20
  2148.                  debug_flag                                    20
  2149.                  buy_armour                                    21
  2150.                  buy_shells                                    21
  2151.                  shells_left                                   21
  2152.                  get_local_map                                 22
  2153.                  invisibility                                  22
  2154.                  get_shell_status                              23
  2155.                  isinvisible                                   23
  2156.                  atan2                                         23
  2157.                  get_robot_id                                  23
  2158.                  register_iff                                  23
  2159.                  register_name                                 24
  2160.                  find_name(int id,char far *name_string)       24
  2161.                  get_team_id                                   24
  2162.                  configure                                     25
  2163.  
  2164.             Assembler functions                                25
  2165.                  SWAPTASK                                      25
  2166.                  MOVEMENT                                      25
  2167.                  SCAN                                          26
  2168.                  SHOOT                                         26
  2169.                  GETXY                                         26
  2170.                  TRANSMIT                                      26
  2171.                  RECEIVE                                       26
  2172.                  DAMAGE                                        27
  2173.                  SPEED                                         27
  2174.                  BATTERY                                       27
  2175.                  TICKS                                         27
  2176.                  SIN                                           27
  2177.                  COS                                           27
  2178.                  TAN                                           28
  2179.                  ATAN                                          28
  2180.                  SQRT                                          28
  2181.                  SET_PATTERN                                   28
  2182.                  DEBUG_FLAG                                    28
  2183.                  BUY ARMOUR                                    28
  2184.                  BUY SHELLS                                    29
  2185.                  SHELLS LEFT                                   29
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.                  GET LOCAL MAP                                 29
  2193.                  INVISIBILITY                                  29
  2194.                  GET SHELL STATUS                              29
  2195.                  IS INVISIBLE                                  30
  2196.                  ATAN2                                         30
  2197.                  GET_ROBOT_ID                                  30
  2198.                  REGISTER_IFF                                  30
  2199.                  CHECK_IFF                                     30
  2200.                  REGISTER_NAME                                 30
  2201.                  FIND_NAME                                     31
  2202.                  GET_TEAM_ID                                   31
  2203.                  CONFIGURE                                     31